Purpose

Attach or detach an event handler to/from an event source.

Syntax

DIM oSource AS InterfaceName

DIM oEvent  AS EventInterface

LET oSource = NEWCOM CLSID $ClassId

LET oEvent  = CLASS "EventClass"

EVENTS FROM oSource CALL oEvent

[statements]

EVENTS END oEvent

Remarks

In the above source code sample, oEvent is an object variable which references an event handler object, and oSource is an object variable which references an event source object which generates events.

The EVENTS FROM statement attaches event handler code to an event source object variable. The object variable oEvent must be declared as a supported event interface, while “EventClass" specifies the class which implements the event handler code. The object variable oSource specifies the event source. EVENTS END detaches the event handler from the event source.

Generally speaking, a server object "sources" events, and a client object "handles" events by supplying a METHOD which is called by the server to perform a user-defined notification. This event handler is code in the client object, which is sometimes referred to as an "event sink" (analogous to the electrical engineering terms source/sink).

One or more clients may choose to "subscribe" to events from a server object by executing the EVENTS FROM statement. The subscription is terminated by execution of the EVENTS END statement. When the server executes RAISEEVENT or OBJECT RAISEEVENT, all clients which have unsubscribed to these events are called. PowerBASIC servers support up to 32 concurrent client subscribers per server object.

Event sources and event handlers may be used within a single module, or through COM services supplied by the Windows operating system.

See also

CLASS, EVENT SOURCE, INTERFACE (Direct), INTERFACE (IDBind), Just what is COM?, OBJECT RAISEEVENT, RAISEEVENT, What is an object, anyway?, What are Connection Points?

Example

#COMPILE EXE

CLASS EvClass AS EVENT

 INTERFACE EvStatus AS EVENT

   INHERIT IUNKNOWN

   METHOD Done

     MSGBOX "Done!"

   END METHOD

 END INTERFACE

END CLASS

CLASS MyClass

 INTERFACE MyMath

   INHERIT IUNKNOWN

   METHOD DoMath

     MSGBOX "Calculating..."   ' Do some math calculations here

     RAISEEVENT EvStatus.Done()

   END METHOD

 END INTERFACE

 EVENT SOURCE EvStatus

END CLASS

FUNCTION PBMAIN()

 DIM oMath   AS MyMath

 DIM oStatus AS EvStatus

 LET oMath   = CLASS "MyClass"

 LET oStatus = CLASS "EvClass"

 EVENTS FROM oMath CALL oStatus

 oMath.DoMath

 EVENTS END oStatus

END FUNCTION